home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Math.java < prev    next >
Text File  |  1998-09-22  |  19KB  |  523 lines
  1. /*
  2.  * @(#)Math.java    1.25 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.lang;
  16. import java.util.Random;
  17.  
  18.  
  19. /**
  20.  * The class <code>Math</code> contains methods for performing basic 
  21.  * numeric operations such as the elementary exponential, logarithm, 
  22.  * square root, and trigonometric functions. 
  23.  * <p>
  24.  * To help ensure portability of Java programs, the definitions of 
  25.  * many of the numeric functions in this package require that they 
  26.  * produce the same results as certain published algorithms. These 
  27.  * algorithms are available from the well-known network library 
  28.  * <code>netlib</code> as the package "Freely Distributable 
  29.  * Math Library" (<code>fdlibm</code>). These algorithms, which 
  30.  * are written in the C programming language, are then to be 
  31.  * understood as executed with all floating-point operations 
  32.  * following the rules of Java floating-point arithmetic. 
  33.  * <p>
  34.  * The network library may be found on the World Wide Web at 
  35.  * <ul><code>
  36.  *   http://netlib.att.com/
  37.  * </code></ul>
  38.  * <p>
  39.  * then perform a keyword search for "<code>fdlibm</code>".
  40.  * <p>
  41.  * The Java math library is defined with respect to the version of 
  42.  * <code>fdlibm</code> dated January 4, 1995. Where 
  43.  * <code>fdlibm</code> provides more than one definition for a 
  44.  * function (such as <code>acos</code>), use the "IEEE 754 core 
  45.  * function" version (residing in a file whose name begins with 
  46.  * the letter <code>e</code>). 
  47.  *
  48.  * @author  unascribed
  49.  * @version 1.25, 07/01/98
  50.  * @since   JDK1.0
  51.  */
  52.  
  53. public final class Math {
  54.  
  55.     /**
  56.      * Don't let anyone instantiate this class.
  57.      */
  58.     private Math() {}
  59.  
  60.     /**
  61.      * The <code>double</code> value that is closer than any other to 
  62.      * <code>e</code>, the base of the natural logarithms. 
  63.      *
  64.      * @since   JDK1.0
  65.      */
  66.     public static final double E = 2.7182818284590452354;
  67.  
  68.     /**
  69.      * The <code>double</code> value that is closer than any other to 
  70.      * <i>pi</i>, the ratio of the circumference of a circle to its diameter. 
  71.      *
  72.      * @since   JDK1.0
  73.      */
  74.     public static final double PI = 3.14159265358979323846;
  75.  
  76.     /**
  77.      * Returns the trigonometric sine of an angle.
  78.      *
  79.      * @param   a   an angle, in radians.
  80.      * @return  the sine of the argument.
  81.      * @since   JDK1.0
  82.      */
  83.     public static native double sin(double a);
  84.     
  85.     /**
  86.      * Returns the trigonometric cosine of an angle.
  87.      *
  88.      * @param   a   an angle, in radians.
  89.      * @return  the cosine of the argument.
  90.      * @since   JDK1.0
  91.      */
  92.     public static native double cos(double a);
  93.    
  94.     /**
  95.      * Returns the trigonometric tangent of an angle.
  96.      *
  97.      * @param   a   an angle, in radians.
  98.      * @return  the tangent of the argument.
  99.      * @since   JDK1.0
  100.      */
  101.     public static native double tan(double a);
  102.  
  103.     /**
  104.      * Returns the arc sine of an angle, in the range of -<i>pi</i>/2 through
  105.      * <i>pi</i>/2.
  106.      *
  107.      * @param   a   an angle, in radians.
  108.      * @return  the arc sine of the argument.
  109.      * @since   JDK1.0
  110.      */
  111.     public static native double asin(double a);
  112.  
  113.     /**
  114.      * Returns the arc cosine of an angle, in the range of 0.0 through
  115.      * <i>pi</i>.
  116.      *
  117.      * @param   a   an angle, in radians.
  118.      * @return  the arc cosine of the argument.
  119.      * @since   JDK1.0
  120.      */
  121.     public static native double acos(double a); 
  122.  
  123.     /**
  124.      * Returns the arc tangent of an angle, in the range of -<i>pi</i>/2
  125.      * through <i>pi</i>/2.
  126.      *
  127.      * @param   a   an angle, in radians.
  128.      * @return  the arc tangent of the argument.
  129.      * @since   JDK1.0
  130.      */
  131.     public static native double atan(double a);
  132.  
  133.     /**
  134.      * Returns the exponential number <i>e</i> (i.e., 2.718...) raised to
  135.      * the power of a <code>double</code> value.
  136.      *
  137.      * @param   a   a <code>double</code> value.
  138.      * @return  the value <i>e</i><sup>a</sup>, where <i>e</i> is the base of
  139.      *          the natural logarithms.
  140.      * @since   JDK1.0
  141.      */
  142.     public static native double exp(double a);
  143.  
  144.     /**
  145.      * Returns the natural logarithm (base <i>e</i>) of a <code>double</code>
  146.      * value.
  147.      *
  148.      * @param   a   a number greater than <code>0.0</code>.
  149.      * @return  the value ln <code>a</code>, the natural logarithm of
  150.      *          <code>a</code>.
  151.      * @since   JDK1.0
  152.      */
  153.     public static native double log(double a);
  154.  
  155.     /**
  156.      * Returns the square root of a <code>double</code> value.
  157.      *
  158.      * @param   a   a <code>double</code> value.
  159.      * <!--@return  the value of √ <code>a</code>.-->
  160.      * @return  the square root of <code>a</code>.
  161.      *          If the argument is NaN or less than zero, the result is NaN.
  162.      * @since   JDK1.0
  163.      */
  164.     public static native double sqrt(double a);
  165.  
  166.     /**
  167.      * Computes the remainder operation on two arguments as prescribed 
  168.      * by the IEEE 754 standard.
  169.      * The remainder value is mathematically equal to 
  170.      * <code>f1 - f2</code> × <i>n</i>,
  171.      * where <i>n</i> is the mathematical integer closest to the exact 
  172.      * mathematical value of the quotient <code>f1/f2</code>, and if two 
  173.      * mathematical integers are equally close to <code>f1/f2</code>, 
  174.      * then <i>n</i> is the integer that is even. If the remainder is 
  175.      * zero, its sign is the same as the sign of the first argument. 
  176.      *
  177.      * @param   f1   the dividend.
  178.      * @param   f2   the divisor.
  179.      * @return  the remainder when <code>f1</code> is divided by
  180.      *          <code>f2</code>.
  181.      * @since   JDK1.0
  182.      */
  183.     public static native double IEEEremainder(double f1, double f2);
  184.  
  185.     /**
  186.      * Returns the smallest (closest to negative infinity) 
  187.      * <code>double</code> value that is not less than the argument and is 
  188.      * equal to a mathematical integer. 
  189.      *
  190.      * @param   a   a <code>double</code> value.
  191.      * <!--@return  the value ⌈ <code>a</code> ⌉.-->
  192.      * @return  the smallest (closest to negative infinity) 
  193.      *          <code>double</code> value that is not less than the argument
  194.      *          and is equal to a mathematical integer. 
  195.      * @since   JDK1.0
  196.      */
  197.     public static native double ceil(double a);
  198.  
  199.     /**
  200.      * Returns the largest (closest to positive infinity) 
  201.      * <code>double</code> value that is not greater than the argument and 
  202.      * is equal to a mathematical integer. 
  203.      *
  204.      * @param   a   a <code>double</code> value.
  205.      * @param   a   an assigned value.
  206.      * <!--@return  the value ⌊ <code>a</code> ⌋.-->
  207.      * @return  the largest (closest to positive infinity) 
  208.      *          <code>double</code> value that is not greater than the argument
  209.      *          and is equal to a mathematical integer. 
  210.      * @since   JDK1.0
  211.      */
  212.     public static native double floor(double a);
  213.  
  214.     /**
  215.      * returns the closest integer to the argument. 
  216.      *
  217.      * @param   a   a <code>double</code> value.
  218.      * @return  the closest <code>double</code> value to <code>a</code> that is
  219.      *          equal to a mathematical integer. If two <code>double</code>
  220.      *          values that are mathematical integers are equally close to the
  221.      *          value of the argument, the result is the integer value that
  222.      *          is even.
  223.      * @since   JDK1.0
  224.      */
  225.     public static native double rint(double a);
  226.  
  227.     /**
  228.      * Converts rectangular coordinates (<code>b</code>, <code>a</code>)
  229.      * to polar (r, <i>theta</i>).
  230.      * This method computes the phase <i>theta</i> by computing an arc tangent
  231.      * of <code>b/a</code> in the range of -<i>pi</i> to <i>pi</i>.
  232.      *
  233.      * @param   a   a <code>double</code> value.
  234.      * @param   b   a <code>double</code> value.
  235.      * @return  the <i>theta</i> component of the point
  236.      *          (<i>r</i>, <i>theta</i>)
  237.      *          in polar coordinates that corresponds to the point
  238.      *          (<i>b</i>, <i>a</i>) in Cartesian coordinates.
  239.      * @since   JDK1.0
  240.      */
  241.     public static native double atan2(double a, double b);
  242.  
  243.  
  244.     /**
  245.      * Returns of value of the first argument raised to the power of the
  246.      * second argument.
  247.      * <p>
  248.      * If (<code>a == 0.0</code>), then <code>b</code> must be
  249.      * greater than <code>0.0</code>; otherwise an exception is thrown. 
  250.      * An exception also will occur if (<code>a <= 0.0</code>)
  251.      * and <code>b</code> is not equal to a whole number.
  252.      *
  253.      * @param   a   a <code>double</code> value.
  254.      * @param   b   a <code>double</code> value.
  255.      * @return  the value <code>a<sup>b</sup></code>.
  256.      * @exception ArithmeticException  if (<code>a == 0.0</code>) and
  257.      *              (<code>b <= 0.0</code>), or
  258.      *              if (<code>a <= 0.0</code>) and <code>b</code>
  259.      *              is not equal to a whole number.
  260.      * @since   JDK1.0
  261.      */
  262.     public static native double pow(double a, double b);
  263.  
  264.     /**
  265.      * Returns the closest <code>int</code> to the argument. 
  266.      * <p>
  267.      * If the argument is negative infinity or any value less than or 
  268.      * equal to the value of <code>Integer.MIN_VALUE</code>, the result is 
  269.      * equal to the value of <code>Integer.MIN_VALUE</code>. 
  270.      * <p>
  271.      * If the argument is positive infinity or any value greater than or 
  272.      * equal to the value of <code>Integer.MAX_VALUE</code>, the result is 
  273.      * equal to the value of <code>Integer.MAX_VALUE</code>. 
  274.      *
  275.      * @param   a   a <code>float</code> value.
  276.      * @return  the value of the argument rounded to the nearest
  277.      *          <code>int</code> value.
  278.      * @see     java.lang.Integer#MAX_VALUE
  279.      * @see     java.lang.Integer#MIN_VALUE
  280.      * @since   JDK1.0
  281.      */
  282.     public static int round(float a) {
  283.     return (int)floor(a + 0.5f);
  284.     }
  285.  
  286.     /**
  287.      * Returns the closest <code>long</code> to the argument. 
  288.      * <p>
  289.      * If the argument is negative infinity or any value less than or 
  290.      * equal to the value of <code>Long.MIN_VALUE</code>, the result is 
  291.      * equal to the value of <code>Long.MIN_VALUE</code>. 
  292.      * <p>
  293.      * If the argument is positive infinity or any value greater than or 
  294.      * equal to the value of <code>Long.MAX_VALUE</code>, the result is 
  295.      * equal to the value of <code>Long.MAX_VALUE</code>. 
  296.      *
  297.      * @param   a   a <code>double</code> value.
  298.      * @return  the value of the argument rounded to the nearest
  299.      *          <code>long</code> value.
  300.      * @see     java.lang.Long#MAX_VALUE
  301.      * @see     java.lang.Long#MIN_VALUE
  302.      * @since   JDK1.0
  303.      */
  304.     public static long round(double a) {
  305.     return (long)floor(a + 0.5d);
  306.     }
  307.  
  308.     private static Random randomNumberGenerator;
  309.  
  310.     /**
  311.      * Returns a random number between <code>0.0</code> and <code>1.0</code>.
  312.      * Random number generators are often referred to as pseudorandom number 
  313.      * generators because the numbers produced tend to repeat themselves after
  314.      * a period of time.
  315.      *  
  316.      * @return  a pseudorandom <code>double</code> between <code>0.0</code>
  317.      *          and <code>1.0</code>.
  318.      * @see     java.util.Random#nextDouble()
  319.      * @since   JDK1.0
  320.      */
  321.     public static synchronized double random() {
  322.         if (randomNumberGenerator == null)
  323.             randomNumberGenerator = new Random();
  324.         return randomNumberGenerator.nextDouble();
  325.     }
  326.  
  327.     /**
  328.      * Returns the absolute value of an <code>int</code> value.
  329.      * If the argument is not negative, the argument is returned.
  330.      * If the argument is negative, the negation of the argument is returned. 
  331.      * <p>
  332.      * Note that if the argument is equal to the value of 
  333.      * <code>Integer.MIN_VALUE</code>, the most negative representable 
  334.      * <code>int</code> value, the result is that same value, which is 
  335.      * negative. 
  336.      *
  337.      * @param   a   an <code>int</code> value.
  338.      * @return  the absolute value of the argument.
  339.      * @see     java.lang.Integer#MIN_VALUE
  340.      * @since   JDK1.0
  341.      */
  342.     public static int abs(int a) {
  343.     return (a < 0) ? -a : a;
  344.     }
  345.  
  346.     /**
  347.      * Returns the absolute value of a <code>long</code> value.
  348.      * If the argument is not negative, the argument is returned.
  349.      * If the argument is negative, the negation of the argument is returned. 
  350.      * <p>
  351.      * Note that if the argument is equal to the value of 
  352.      * <code>Long.MIN_VALUE</code>, the most negative representable 
  353.      * <code>long</code> value, the result is that same value, which is 
  354.      * negative. 
  355.      *
  356.      * @param   a   a <code>long</code> value.
  357.      * @return  the absolute value of the argument.
  358.      * @see     java.lang.Long#MIN_VALUE
  359.      * @since   JDK1.0
  360.      */
  361.     public static long abs(long a) {
  362.     return (a < 0) ? -a : a;
  363.     }
  364.  
  365.     /**
  366.      * Returns the absolute value of a <code>float</code> value.
  367.      * If the argument is not negative, the argument is returned.
  368.      * If the argument is negative, the negation of the argument is returned. 
  369.      *
  370.      * @param   a   a <code>float</code> value.
  371.      * @return  the absolute value of the argument.
  372.      * @since   JDK1.0
  373.      */
  374.     public static float abs(float a) {
  375.     return (a < 0) ? -a : a;
  376.     }
  377.   
  378.     /**
  379.      * Returns the absolute value of a <code>double</code> value.
  380.      * If the argument is not negative, the argument is returned.
  381.      * If the argument is negative, the negation of the argument is returned. 
  382.      *
  383.      * @param   a   a <code>double</code> value.
  384.      * @return  the absolute value of the argument.
  385.      * @since   JDK1.0
  386.      */
  387.     public static double abs(double a) {
  388.     return (a < 0) ? -a : a;
  389.     }
  390.  
  391.     /**
  392.      * Returns the greater of two <code>int</code> values.
  393.      *
  394.      * @param   a   an <code>int</code> value.
  395.      * @param   b   an <code>int</code> value.
  396.      * @return  the larger of <code>a</code> and <code>b</code>.
  397.      * @since   JDK1.0
  398.      */
  399.     public static int max(int a, int b) {
  400.     return (a >= b) ? a : b;
  401.     }
  402.  
  403.     /**
  404.      * Returns the greater of two <code>long</code> values.
  405.      *
  406.      * @param   a   a <code>long</code> value.
  407.      * @param   b   a <code>long</code> value.
  408.      * @return  the larger of <code>a</code> and <code>b</code>.
  409.      * @since   JDK1.0
  410.      */
  411.     public static long max(long a, long b) {
  412.     return (a >= b) ? a : b;
  413.     }
  414.  
  415.     private static long negativeZeroFloatBits = Float.floatToIntBits(-0.0f);
  416.     private static long negativeZeroDoubleBits = Double.doubleToLongBits(-0.0d);
  417.  
  418.     /**
  419.      * Returns the greater of two <code>float</code> values.  If either value
  420.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  421.      * the numerical comparison operators, this method considers negative zero
  422.      * to be strictly smaller than positive zero.
  423.      *
  424.      * @param   a   a <code>float</code> value.
  425.      * @param   b   a <code>float</code> value.
  426.      * @return  the larger of <code>a</code> and <code>b</code>.
  427.      * @since   JDK1.0
  428.      */
  429.     public static float max(float a, float b) {
  430.         if (a != a) return a;    // a is NaN
  431.     if ((a == 0.0f) && (b == 0.0f)
  432.         && (Float.floatToIntBits(a) == negativeZeroFloatBits)) {
  433.         return b;
  434.     }
  435.     return (a >= b) ? a : b;
  436.     }
  437.  
  438.     /**
  439.      * Returns the greater of two <code>double</code> values.  If either value
  440.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  441.      * the numerical comparison operators, this method considers negative zero
  442.      * to be strictly smaller than positive zero.
  443.      *
  444.      * @param   a   a <code>double</code> value.
  445.      * @param   b   a <code>double</code> value.
  446.      * @return  the larger of <code>a</code> and <code>b</code>.
  447.      * @since   JDK1.0
  448.      */
  449.     public static double max(double a, double b) {
  450.         if (a != a) return a;    // a is NaN
  451.     if ((a == 0.0d) && (b == 0.0d)
  452.         && (Double.doubleToLongBits(a) == negativeZeroDoubleBits)) {
  453.         return b;
  454.     }
  455.     return (a >= b) ? a : b;
  456.     }
  457.  
  458.     /**
  459.      * Returns the smaller of two <code>int</code> values.
  460.      *
  461.      * @param   a   an <code>int</code> value.
  462.      * @param   b   an <code>int</code> value.
  463.      * @return  the smaller of <code>a</code> and <code>b</code>.
  464.      * @since   JDK1.0
  465.      */
  466.     public static int min(int a, int b) {
  467.     return (a <= b) ? a : b;
  468.     }
  469.  
  470.     /**
  471.      * Returns the smaller of two <code>long</code> values.
  472.      *
  473.      * @param   a   a <code>long</code> value.
  474.      * @param   b   a <code>long</code> value.
  475.      * @return  the smaller of <code>a</code> and <code>b</code>.
  476.      * @since   JDK1.0
  477.      */
  478.     public static long min(long a, long b) {
  479.     return (a <= b) ? a : b;
  480.     }
  481.  
  482.     /**
  483.      * Returns the smaller of two <code>float</code> values.  If either value
  484.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  485.      * the numerical comparison operators, this method considers negative zero
  486.      * to be strictly smaller than positive zero.
  487.      *
  488.      * @param   a   a <code>float</code> value.
  489.      * @param   b   a <code>float</code> value.
  490.      * @return  the smaller of <code>a</code> and <code>b.</code>
  491.      * @since   JDK1.0
  492.      */
  493.     public static float min(float a, float b) {
  494.         if (a != a) return a;    // a is NaN
  495.     if ((a == 0.0f) && (b == 0.0f)
  496.         && (Float.floatToIntBits(b) == negativeZeroFloatBits)) {
  497.         return b;
  498.     }
  499.     return (a <= b) ? a : b;
  500.     }
  501.  
  502.     /**
  503.      * Returns the smaller of two <code>double</code> values.  If either value
  504.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  505.      * the numerical comparison operators, this method considers negative zero
  506.      * to be strictly smaller than positive zero.
  507.      *
  508.      * @param   a   a <code>double</code> value.
  509.      * @param   b   a <code>double</code> value.
  510.      * @return  the smaller of <code>a</code> and <code>b</code>.
  511.      * @since   JDK1.0
  512.      */
  513.     public static double min(double a, double b) {
  514.         if (a != a) return a;    // a is NaN
  515.     if ((a == 0.0d) && (b == 0.0d)
  516.         && (Double.doubleToLongBits(b) == negativeZeroDoubleBits)) {
  517.         return b;
  518.     }
  519.     return (a <= b) ? a : b;
  520.     }
  521.  
  522. }
  523.